Node / meshtastic / Meshtastic-Android / files / specs / 20260511-211823-compose-screenshot-testing / quickstart.md

Displaying Rendered • View raw • Download

Feature: 018-compose-screenshot-testing

This guide explains how to add a new preview composable and wire it into the screenshot test suite.

• JDK 21, T383838ANDROID_HOME set, proto submodule initialized

• T383838android.experimental.enableScreenshotTest=true in T383838gradle.properties

Add a T383838@Preview or T383838@PreviewLightDark composable in your module's T383838commonMain:

T282828

Tf0883e@PreviewLightDark

Tf0883e@Composable

Tff7b72fun Td2a8ffMyComponentPreviewTb4b4b4(Tb4b4b4) Tb4b4b4{

Te6edf3AppTheme Tb4b4b4{

Te6edf3MyComponentTb4b4b4(

Te6edf3title Tff7b72= Ta5d6ff"Ta5d6ffSample TitleTa5d6ff"Tb4b4b4,

Te6edf3subtitle Tff7b72= Ta5d6ff"Ta5d6ffSample subtitle textTa5d6ff"Tb4b4b4,

Tb4b4b4)

Tb4b4b4}

Tb4b4b4}

Rules:

• Visibility: public (no modifier) — the screenshot-tests module must import it across module boundaries (T383838internal does NOT work across modules)

• Theme: Always wrap in T383838AppTheme { ... }

• Data: Use hardcoded synthetic values — never real user data or PII

• Dependencies: No ViewModel, DI, or network access — stateless only

• Determinism: Avoid time-dependent or random data (e.g., T383838Channel.getRandomKey(), relative timestamps like "last heard X ago") — these cause flaky diffs

Create or update a file in the screenshot-tests module:

T282828

Tf0883e@PreviewTest

Tf0883e@PreviewLightDark

Tf0883e@Composable

Tff7b72fun Td2a8ffMyComponentScreenshotTestTb4b4b4(Tb4b4b4) Tb4b4b4{

Te6edf3MyComponentPreviewTb4b4b4(Tb4b4b4)

Tb4b4b4}

Rules:

• Must have T383838@PreviewTest annotation (from T383838com.android.tools.screenshot)

• Must also have the same T383838@Preview or T383838@PreviewLightDark as the source preview

• Function can be T383838public (default) — this is a test, not API surface

T282828

Reference images are saved to T383838screenshot-tests/src/screenshotTestDebug/reference/.

T282828

If no UI changes were made, this passes. If the rendered output differs from references, it fails and produces an HTML diff report at T383838screenshot-tests/build/reports/screenshotTest/preview/debug/index.html.

T282828

Reference images must be in version control so CI can validate against them.

If you intentionally change a component's appearance:

1. Run the update task to regenerate references:

T282828

2. Review the updated PNGs in T383838screenshot-tests/src/screenshotTestDebug/reference/

3. Commit the updated images

4. Validate:

T282828

Preview not found by CST: Ensure the preview function is public (no modifier, not T383838private or T383838internal) and the T383838screenshot-tests module has an T383838implementation(project(":your:module")) dependency.

Theme not applied: Wrap preview content in T383838AppTheme { ... }. The theme is in T383838core:ui.

Reference image diff on CI but not locally: Reference images should be generated on CI (Ubuntu) or with an identical JDK version. Minor font rendering differences between macOS and Linux are absorbed by the T383838imageDifferenceThreshold (0.05%).

T383838@PreviewTest not resolving: Ensure T383838screenshotTestImplementation(libs.screenshot.validation.api) is in T383838screenshot-tests/build.gradle.kts.